home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RIAppLib.doc < prev    next >
Encoding:
Text File  |  1995-01-30  |  7.7 KB  |  273 lines
  1. -----------------------------------------------------------------------------
  2. ====                     RI App Library V1.4 (C)1994              ====
  3. -----------------------------------------------------------------------------
  4.  
  5.                           Written By Steven Matty
  6.                         ©1994 Leading Edge Software
  7.  
  8.  
  9.                            !!!! IMPORTANT !!!!
  10.         *******************************************
  11.         *   For New Features See Bottom Of Text   *
  12.                 *   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   *
  13.                 *******************************************
  14.  
  15.  
  16. This small library provides quick and easy to use commands for accessing
  17. AppWindows, AppIcons and AppMenus.
  18.  
  19. An AppWindow is a window on the Workbench screen which will allow you
  20. to drag file(s) from into it, instead of ploughing through file-requesters.
  21.  
  22. An AppMenu adds a menu item to the "Tools" menu of the Workbench. It is
  23. normally used for when the program is 'sleeping' and the user wishes to
  24. wake it up. In addition, if any files are selected and the menu item
  25. is selected these are passed to the program.
  26.  
  27. An AppIcon is just like a normal file icon on the Workbench except it
  28. allows you to drop file(s) onto it, or to double-click it to wake
  29. up the program.
  30.  
  31. These features require at Workbench v2.0 or higher.
  32.  
  33. Command List:
  34.  
  35.   AppEvent()
  36.   AppEventCode()
  37.   AppEventID()
  38.   AddAppWindow()
  39.   AddAppIcon()
  40.   AddAppMenu()
  41.   DelAppWindow()
  42.   DelAppIcon()
  43.   DelAppMenu()
  44.   NextAppFile()
  45.   AppFile()
  46.   AppNumFiles()
  47.  
  48.  
  49. Function : AppEvent
  50. ------------------------------------------------------------------------------
  51. Modes  : Amiga
  52. Syntax : status=AppEvent
  53.  
  54. This command checks to see whether or not an 'App'Event (e.g. File
  55. dropped onto an AppIcon or Menu Item selected) has occurred.
  56.  
  57. This function will return 0 if no event has occurred, else
  58. $80000 if :
  59.     An AppMenu was selected
  60.         An AppIcon was double-clicked
  61.         A File Was Dragged Into An AppWindow
  62.         A File Was Dragged Onto An AppIcon
  63.  
  64.  
  65. ********
  66. * NOTE * : This function no longer returns the number of files
  67. ********   selected. $80000 is returned instead of -1.
  68.            See AppNumFiles().
  69.  
  70. e.g.
  71.  
  72.   Repeat
  73.     VWait
  74.     appev.l=AppEvent        ; Has something happened
  75.   Until appev
  76.   If appev=$80000
  77.     NPrint "An AppEvent Occurred! !"
  78.   EndIf
  79.  
  80.  
  81. Function : AddAppWindow
  82. -------------------------------------------------------------------------------
  83. Modes  : Amiga
  84. Syntax : success=AddAppWindow(windownumber)
  85.  
  86. This command attempts to make the window specified by 'windownumber' to become
  87. an AppWindow. -1 means success, 0 means failure. There is a limit of 16
  88. AppWindows open at any one time.
  89.  
  90.  
  91. Function : AddAppIcon
  92. -------------------------------------------------------------------------------
  93. Modes  : Amiga
  94. Syntax : success=AddAppIcon(id,text$,iconname$)
  95.  
  96. This command attempts to place an AppIcon onto the Workbench desktop.
  97. ID is a unique identification number. Text$ is text to display underneath
  98. the AppIcon and Iconname$ is the name of the file to use the Icon imagery.
  99. -1 means success, 0 means failure. There is a limit of 16 AppIcons.
  100. e.g.
  101.  
  102.   suc=AddAppIcon(0,"QuickFormat","SYS:System/Format")
  103.   If suc=0 Then End
  104.   
  105.  
  106. Function : AddAppMenu
  107. -------------------------------------------------------------------------------
  108. Modes  : Amiga
  109. Syntax : success=AddAppMenu(id,text$)
  110.  
  111. This command tries to add 'text$' to the Tools menu of Workbench.
  112. ID is a unique identification number. Returns -1 for success, 0 for failure.
  113. There is a limit of 16 AppMenu items.
  114.  
  115. e.g.
  116.  
  117.   suc=AddAppMenu(0,"Wakey Wakey")
  118.   If suc=0 Then End
  119.  
  120.  
  121. Function : AppEventCode
  122. -------------------------------------------------------------------------------
  123. Modes  : Amiga
  124. Syntax : apptype=AppEventCode
  125.  
  126. This function will return the type of App object which caused the event.
  127. 0=No Event Occurred
  128. 1=AppWindow
  129. 2=AppIcon
  130. 3=AppMenu
  131.  
  132. e.g.
  133.  
  134.   Repeat
  135.     VWait
  136.     appev.l=AppEvent        ; Has something happened
  137.   Until appev
  138.   Select AppEventCode
  139.     Case 1
  140.       NPrint "An AppWindow caused this!"
  141.     Case 2
  142.       NPrint "An AppIcon caused this!"
  143.     Case 3
  144.       NPrint "An AppMenu caused this!"
  145.   End Select
  146.  
  147.  
  148. Function : AppEventID
  149. ------------------------------------------------------------------------------
  150. Modes  : Amiga
  151. Syntax : idnumber=AppEventID
  152.  
  153.   This will return the object ID number which caused the AppEvent.
  154.   This ID number refers to the one which was used in 
  155.   AddAppIcon/AddAppWindow/AddAppWindow.
  156.  
  157.   -1 means that no AppEvent occurred.
  158.  
  159.  
  160. Function : NextAppFile
  161. ------------------------------------------------------------------------------
  162. Modes  : Amiga
  163. Syntax : filename$=NextAppFile
  164.  
  165.   This will return the full path and filename for the file/drawer/volume
  166.   which was selected when an AppEvent occurred.  If a directory was selected
  167.   then a '/' is appended to file name. If a volume (e.g. a Disk) was
  168.   selected then a ":" is appended.
  169.  
  170.   An empty string means nothing was selected.
  171.  
  172.   e.g.
  173.   ; AppStuff initalized
  174.   Repeat
  175.     VWait
  176.     appev.l=AppEvent
  177.   Until appev=$80000      ; repeat until some files are selected.
  178.   numfiles.l=AppNumFiles
  179.   For n=1 To numfiles
  180.     NPrint "File number "+str$(n)+" is "+NextAppFile
  181.   Next n
  182.  
  183.  
  184. Function : AppNumFiles
  185. ------------------------------------------------------------------------------
  186. Modes  : Amiga
  187. Syntax : numfiles=AppNumFiles
  188.  
  189.   This will return the number of files selected when the AppEvent occurred.
  190.   
  191.  
  192. Function : AppFile
  193. ------------------------------------------------------------------------------
  194. Modes  : Amiga
  195. Syntax : filename$=AppFile(file#)
  196.  
  197.   This will return the full path and filename for the file/drawer/volume
  198.   which was selected when an AppEvent occurred. The file# parameter
  199.   specifies which file to return. If a directory was selected then a '/'
  200.   is appended to file name. If a volume (e.g. a Disk) was selected then
  201.   a ":" is appended.
  202.  
  203.   An empty string means nothing was selected.
  204.  
  205.   e.g.
  206.   ; AppStuff initalized
  207.   Repeat
  208.     VWait
  209.     appev.l=AppEvent
  210.   Until appev=$80000      ; repeat until some files are selected.
  211.   numfiles.l=AppNumFiles
  212.   For n=1 To numfiles
  213.     NPrint "File number "+str$(n)+" is "+AppFile(n)
  214.   Next n
  215.  
  216.  
  217. Function: DelAppWindow
  218. ------------------------------------------------------------------------------
  219. Modes  : Amiga
  220. Syntax : success=DelAppWindow[(number)]
  221.  
  222. These commands will remove the AppWindow from the system and free up the
  223. associated message port.
  224.  
  225.  
  226. Function: DelAppIcon
  227. ------------------------------------------------------------------------------
  228. Modes  : Amiga
  229. Syntax : success=DelAppIcon[(id)]
  230.  
  231. These commands will remove the AppIcon from the system and free up the
  232. associated message port.
  233.  
  234.  
  235. Function: DelAppMenu
  236. ------------------------------------------------------------------------------
  237. Modes  : Amiga
  238. Syntax : success=DelAppMenu[(id)]
  239.  
  240. These commands will remove the AppMenu from the system and free up the
  241. associated message port.
  242.  
  243. ==============================================================================
  244.                               VERSION HISTORY
  245. ==============================================================================
  246.  
  247. Version 1.0
  248. ~~~~~~~~~~~
  249. First release using old commands
  250.  
  251.  
  252. Version 1.1
  253. ~~~~~~~~~~~
  254. Re-written from scratch now handles multiple files and is structured
  255. more like the standard Intuition event handling.
  256.  
  257. Version 1.2
  258. ~~~~~~~~~~~
  259. Fixed memory drain. There still seems to be some loss somewhere
  260. Need to add WaitAppEvent which waits for AppEvents + Normal events
  261. instead of a Repeat..VWait..Until loop.
  262.  
  263. Version 1.3
  264. ~~~~~~~~~~~
  265. Re-wrote to allocate memory on run-time. Saved approx 1k off
  266. library size.
  267.  
  268. Version 1.4
  269. ~~~~~~~~~~~
  270. Changed AppEvent to return 0 for no event or $80000 for AppEvent.
  271. No longer returns number of files in AppEvent. Added AppNumFiles
  272. for this. Also changed Blitz Windowslib to allow WaitEvent to capture
  273. AppEvents.